<?php
// $Id$
/**
 * This file contains {@link VersionHistory} which is part of the PHP Content 
 * Repository (phpCR), a derivative of the Java Content Repository JSR-170, and 
 * is licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 * @subpackage Level2
 */

/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/../phpCR.library.php');
phpCR::loadInterface('Version', '/version');


/**
* A {@link VersionHistory} object wraps an nt:versionHistory
 * {@link Node}. It provides convenient access to version history information.
 *
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 * @subpackage Level2
 */
interface VersionHistory
{
   /**
    * Returns the root version of this version history.
    *
    * @return object
    *   A {@link Version} object.
    *
    * @throws {@link RepositoryException}
    *   If an error occurs.
    */
    public function getRootVersion();
    
    
   /**
    * Returns an iterator over all the versions within this version history.
    *
    * The order of the returned objects will not necessarily correspond to the
    * order of versions in terms of the successor relation. To traverse the
    * version graph one must traverse the jcr:successor REFERENCE
    * properties starting with the root version.
    *
    * @return object
    *   A {@link VersionIterator} object.
    * @throws {@link RepositoryException}
    *   If an error occurs.
    */
    public function getAllVersions();
    
    
   /**
    * Retrieves a particular version from this version history by its name or
    * date.
    *
    * <b>PHP Note</b>: As PHP does not offer a Calendar class as a core part
    * of its distribution, $date can not be an object.  It must be 
    * formatted according to the 
    * {@link http://www.w3.org/TR/NOTE-datetime ISO8601 specifications}.  At 
    * some future point, phpCR may offer a simple Calendar object to encapsulate
    * this parameter, at which time this will require an object for the 
    * parameter.
    *
    * <b>PHP Note</b>: A simple preg_match() can determine if 
    * $retrieve is a date.
    *
    * @param string
    *   A version name or date
    * @return object 
    *   A {@link Version} object.
    *
    * @throws {@link RepositoryException}
    *   If an error occurs.
    */
    public function getVersion($retrieve);
    
    
   /**
    * Retrieves a particular version from this version history by version label.
    *
    * @param string
    *   A version label
    * @return object
    *   A {@link Version} object.
    *
    * @throws {@link RepositoryException}
    *   If an error occurs.
    */
    public function getVersionByLabel($label);
}

